%=============================================================================
%=============================================================================

\chapter{General Information}

%-----------------------------------------------------------------------------

\section{Getting the Source Code}

The \hypre{} distribution tar file is available from the Software link of the
\hypre{} web page, \url{http://www.llnl.gov/CASC/hypre/}.  The \hypre{} Software
distribution page allows access to the tar files of the latest and previous
general and beta distributions as well as documentation.

%-----------------------------

\section{Building the Library}

In this and the following several sections, we discuss the steps to install and
use \hypre{} on a Unix-like operating system, such as Linux, AIX, and Mac~OS~X.
Alternatively, the CMake build system \cite{CMakeWebPage} can be used, and is
the best approach for building \hypre{} on Windows systems in particular (see
the \file{INSTALL} file for details).

After unpacking the \hypre{} tar file, the source code will be in the ``src''
sub-directory of a directory named hypre-VERSION, where VERSION is the current
version number (e.g., hypre-1.8.4, with a ``b'' appended for a beta release).

Move to the ``src'' sub-directory to build \hypre{} for the host platform.  The
simplest method is to configure, compile and install the libraries in
\file{./hypre/lib} and \file{./hypre/include} directories, which is accomplished
by:
\begin{verbatim}
   ./configure
   make
\end{verbatim}

NOTE: when executing on an IBM platform \file{configure} must be executed under
the nopoe script (\file{./nopoe ./configure <option> ...<option>}) to force a
single task to be run on the log-in node.

There are many options to \file{configure} and \file{make} to customize such
things as installation directories, compilers used, compile and load flags, etc.

Executing \file{configure} results in the creation of platform specific files
that are used when building the library. The information may include such things
as the system type being used for building and executing, compilers being used,
libraries being searched, option flags being set, etc.  When all of the
searching is done two files are left in the \file{src} directory;
\file{config.status} contains information to recreate the current configuration
and \file{config.log} contains compiler messages which may help in debugging
\file{configure} errors.

Upon successful completion of \file{configure} the file
\file{config/Makefile.config} is created from its template
\file{config/Makefile.config.in} and \hypre{} is ready to be built.

Executing \file{make}, with or without targets being specified, in the
\file{src} directory initiates compiling of all of the source code and building
of the \hypre{} library.  If any errors occur while compiling, the user can edit
the file \file{config/Makefile.config} directly then run \file{make} again;
without having to re-run configure.

When building \hypre{} without the install target, the libraries and include
files will be copied into the default directories, \file{src/hypre/lib} and
\file{src/hypre/include}, respectively.

When building \hypre{} using the install target, the libraries and include files
will be copied into the directories that the user specified in the options to
\file{configure}, e.g. \file{--prefix=/usr/apps}.  If none were specified the
default directories, \file{src/hypre/lib} and \file{src/hypre/include}, are
used.

%-----------------------------

\subsection{Configure Options}\label{config_options}

There are many options to \file{configure} to allow the user to override and
refine the defaults for any system. The best way to find out what options are
available is to display the help package, by executing \file{./configure
--help}, which also includes the usage information.  The user can mix and match
the configure options and variable settings to meet their needs.

Some of the commonly used options include:

\begin{verbatim}
   --enable-debug                 Sets compiler flags to generate information 
                                  needed for debugging.
   --enable-shared                Build shared libraries.
                                  NOTE: in order to use the resulting shared 
                                        libraries the user MUST have the path to
                                        the libraries defined in the environment 
                                        variable LD_LIBRARY_PATH. 
   --with-print-errors            Print HYPRE errors
   --with-no-global-partition     Do NOT store a global partition of the data
                                  NOTE: this option reduces storage and improves
                                        performance when using many thousands of
                                        processors (not recommended for < 1000 
                                        processors).


\end{verbatim}

The user can mix and match the configure options and variable settings to meet
their needs.  It should be noted that \hypre{} can be configured with external
BLAS and LAPACK libraries, which can be combined with any other option.  This is
done as follows (currently, both libraries must be configured as external
together):

\begin{verbatim}
      ./configure  --with-blas-lib="blas-lib-name" --with-blas-lib-dirs="path-to-blas-lib" \
                   --with-lapack-lib="lapack-lib-name" --with-lapack-lib-dirs="path-to-lapack-lib"
\end{verbatim}

The output from \file{configure} is several pages long.  It reports the system
type being used for building and executing, compilers being used, libraries
being searched, option flags being set, etc.

%-----------------------------

\subsection{Make Targets}

The make step in building \hypre{} is where the compiling, loading and creation
of libraries occurs.  Make has several options that are called targets.  These
include:
\begin{verbatim}
   help         prints the details of each target

   all          default target in all directories
                compile the entire library
                does NOT rebuild documentation

   clean        deletes all files from the current directory that are 
                   created by building the library

   distclean    deletes all files from the current directory that are created
                   by configuring or building the library

   install      compile the source code, build the library and copy executables,
                    libraries, etc to the appropriate directories for user access

   uninstall    deletes all files that the install target created

   tags         runs etags to create a tags table
                file is named TAGS and is saved in the top-level directory

   test         depends on the all target to be completed
                removes existing temporary installation directories
                creates temporary installation directories
                copies all libHYPRE* and *.h files to the temporary locations
                builds the test drivers; linking to the temporary locations to
                   simulate how application codes will link to HYPRE
\end{verbatim}

%-----------------------------------------------------------------------------

\section{Testing the Library} 

The \kbd{examples} subdirectory contains several codes that can be used to test
the newly created \hypre{} library.  To create the executable versions, move
into the \kbd{examples} subdirectory, enter \kbd{make} then execute the codes as
described in the initial comments section of each source code.

%-----------------------------

\section{Linking to the Library}

An application code linking with \hypre{} must be compiled with
\kbd{-I\$PREFIX/include} and linked with \kbd{-L\$PREFIX/lib -lHYPRE}, where
\kbd{\$PREFIX} is the directory where \hypre{} is installed, default is
\kbd{hypre}, or as defined by the configure option \kbd{--prefix=PREFIX}. As
noted above, if \hypre{} was built as a shared library the user MUST have its
location defined in the environment variable \kbd{LD\_LIBRARY\_PATH}.

As an example of linking with \hypre{}, a user may refer to the \kbd{Makefile}
in the \file{examples} sub-directory.  It is designed to build codes similar to
user applications that link with and call \hypre{}.  All include and linking
flags are defined in the \file{Makefile.config} file by \file{configure}.

%-----------------------------------------------------------------------------

\section{Error Flags}

Every \hypre{} function returns an integer, which is used to indicate errors
during execution.  Note that the error flag returned by a given function
reflects the errors from {\em all} previous calls to \hypre{} functions.  In
particular, a value of zero means that all \hypre{} functions up to (and
including) the current one have completed successfully.  This new error flag
system is being implemented throughout the library, but currently there are
still functions that do not support it.  The error flag value is a combination
of one or a few of the following error codes:
\begin{enumerate}
\item \code{HYPRE\_ERROR\_GENERIC} -- describes a generic error
\item \code{HYPRE\_ERROR\_MEMORY} -- \hypre{} was unable to allocate memory
\item \code{HYPRE\_ERROR\_ARG} -- error in one of the arguments of a \hypre{} function
\item \code{HYPRE\_ERROR\_CONV} -- a \hypre{} solver did not converge as expected
\end{enumerate}
One can use the \code{HYPRE\_CheckError} function to determine exactly which
errors have occurred:
\begin{display} \begin{verbatim}
/* call some HYPRE functions */
hypre_ierr = HYPRE_Function();
/* check if the previously called hypre functions returned error(s) */
if (hypre_ierr)
   /* check if the error with code HYPRE_ERROR_CODE has occurred */
   if (HYPRE_CheckError(hypre_ierr,HYPRE_ERROR_CODE))
\end{verbatim} \end{display}
The corresponding FORTRAN code is
\begin{display} \begin{verbatim}
C header file with hypre error codes
      include 'HYPRE_error_f.h'
C call some HYPRE functions
      call HYPRE_Function(..., hypre_ierr);
C check if the previously called hypre functions returned error(s)
      if (hypre_ierr .ne. 0) then
C check if the error with code HYPRE_ERROR_CODE has occurred
         HYPRE_CheckError(hypre_ierr,HYPRE_ERROR_CODE,check)
         if (check .ne. 0) then
\end{verbatim} \end{display}
The global error flag can also be obtained directly, between calls to other
\hypre{} functions, by calling \code{HYPRE\_GetError()}.  If an argument error
(\code{HYPRE\_ERROR\_ARG}) has occurred, the argument index (counting from 1)
can be obtained from \code{HYPRE\_GetErrorArg()}.  To get a character string
with a description of all errors in a given error flag, use
\begin{display} \begin{verbatim}
HYPRE_DescribeError(int hypre_ierr, char *descr);
\end{verbatim} \end{display}
Finally, if \hypre{} was configured with \code{--with-print-errors}, additional
error information will be printed to the standard error during execution.

%-----------------------------------------------------------------------------

\section{Bug Reporting and General Support}

Simply send and email to \kbd{hypre-support@llnl.gov} to report bugs, request
features, or ask general usage questions.  An {\em issue number} will be
assigned to your email so that we can track progress (we are using an issue
tracking tool called Roundup to do this).

Users should include as much relevant information as possible in their issue
emails, including at a minimum, the \hypre{} version number being used.  For
compile and runtime problems, please also include the machine type, operating
system, MPI implementation, compiler, and any error messages produced.

%-----------------------------------------------------------------------------

\section{Using HYPRE in External FEI Implementations}
\label{LSI_install}
To set up \hypre{} for use in external, e.g. Sandia's, {\tt FEI} implementations
one needs to follow the following steps:
\begin{enumerate}
\item obtain the \hypre{} and Sandia's {\tt FEI} source codes,
\item compile Sandia's {\tt FEI} (fei-2.5.0) to create the
      {\tt fei\_base} library.
\item compile \hypre{}
\begin{enumerate}
\item unpack the archive and go into the \code{src} directory
\item do a 'configure' with the {\tt --with-fei-inc-dir} option set to
      the {\tt FEI} include directory plus other compile options
\item compile with {\tt make install} to create the
      {\tt HYPRE\_LSI} library in {\tt hypre/lib}.
\end{enumerate}
\item call the {\tt FEI} functions in your application code (as shown in
      Chapters \ref{ch-FEI} and \ref{ch-Solvers})
\begin{enumerate}
\item include {\tt cfei-hypre.h} in your file
\item include {\tt FEI\_Implementation.h} in your file
\end{enumerate}
\item Modify your \code{Makefile}
\begin{enumerate}
\item include \hypre{}'s {\tt include} and {\tt lib} directories in the search paths.
\item Link with \code{-lfei_base -lHYPRE_LSI}.
Note that the order in which the libraries are listed may be important.
\end{enumerate}
\end{enumerate}
Building an application executable often requires linking with many different
software packages, and many software packages use some LAPACK and/or BLAS
functions.  In order to alleviate the problem of multiply defined functions
at link time, it is recommended that all software libraries are stripped of
all LAPACK and BLAS function definitions.  These LAPACK and BLAS functions 
should then be resolved at link time by linking with the system LAPACK and
BLAS libraries (e.g. dxml on DEC cluster).  Both \hypre{} and SuperLU were
built with this in mind.  However, some other software library files needed
may have the BLAS functions defined in them.  To avoid the problem of
multiply defined functions, it is recommended that the offending library
files be stripped of the BLAS functions.

%Comments about \hypre{}'s finite element interface can be directed
%to Charles Tong (925-422-3411, chtong@llnl.gov).

%-----------------------------------------------------------------------------

\section{Calling HYPRE from Other Languages}

The \hypre{} library can be called from a variety of languages.  This is
currently provided through two basic mechanisms:
\begin{itemize}
\item The Babel interfaces described in Chapter~\ref{ch-babel} utilize the Babel
tool to provide the most extensive language support (note that the \hypre{}
library is moving towards using the Babel tool as its primary means of getting
language interoperability).
\item A Fortran interface is manually supported to mirror the ``native'' C
interface used throughout most of this manual.  We describe this interface next.
\end{itemize}

Typically, the Fortran subroutine name is the same as the C name, unless it is
longer than 31 characters.  In these situations, the name is condensed to 31
characters, usually by simple truncation.  For now, users should look at the
Fortran test drivers (*.f codes) in the \code{test} directory for the correct
condensed names.  In the future, this aspect of the interface conversion will be
made consistent and straightforward.

The Fortran subroutine argument list is always the same as the corresponding C
routine, except that the error return code \code{ierr} is always last.
Conversion from C parameter types to Fortran argument type is summarized in
Table \ref{table-fortran-interface-types}.

\begin{table}
\center
\begin{tabular}{|l|l|}
\hline
C parameter & Fortran argument \\
\hline\hline
\code{int i} & \code{integer i} \\
\code{double d} & \code{double precision d} \\
\code{int *array} & \code{integer array(*)} \\
\code{double *array} & \code{double precision array(*)} \\
\code{char *string} & \code{character string(*)} \\
\code{HYPRE\_Type object} & \code{integer*8 object} \\
\code{HYPRE\_Type *object} & \code{integer*8 object} \\
\hline
\end{tabular}
\caption{%
Conversion from C parameters to Fortran arguments
}
\label{table-fortran-interface-types}
\end{table}

Array arguments in \hypre{} are always of type \code{(int *)} or \code{(double
*)}, and the corresponding Fortran types are simply \code{integer} or
\code{double precision} arrays.  Note that the Fortran arrays may be indexed in
any manner.  For example, an integer array of length \code{N} may be declared in
fortran as either of the following:
\begin{display}
\begin{verbatim}
      integer  array(N)
      integer  array(0:N-1)
\end{verbatim}
\end{display}

\hypre{} objects can usually be declared as in the table because
\code{integer*8} usually corresponds to the length of a pointer.  However, there
may be some machines where this is not the case.  On such machines, the Fortran
type for a \hypre{} object should be an \code{integer} of the appropriate
length.

This simple example illustrates the above information: 

C prototype:
\begin{display}
\begin{verbatim}
int HYPRE_IJMatrixSetValues(HYPRE_IJMatrix  matrix,
                            int  nrows, int  *ncols,
                            const int *rows, const int  *cols,
                            const double  *values);
\end{verbatim}
\end{display}

The corresponding Fortran code for calling this routine is as follows:
\begin{display}
\begin{verbatim}
      integer*8         matrix, 
      integer           nrows, ncols(MAX_NCOLS)
      integer           rows(MAX_ROWS), cols(MAX_COLS)
      double precision  values(MAX_COLS)
      integer           ierr

      call HYPRE_IJMatrixSetValues(matrix, nrows, ncols, rows, cols,
     &                             values, ierr)
\end{verbatim}
\end{display}
